home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / prog / ahelp13.zip / AHELP5.DOC < prev    next >
Text File  |  1993-04-03  |  21KB  |  492 lines
  1.  
  2.                            ***  IMPORTANT!!!  ***
  3.  
  4.  For a printed copy of this user guide, copy this file to your printer.
  5.  
  6.  If you have a previous version of AHELP, the three notes on this page may be
  7.  of interest to you.  Otherwise, proceed to the next page.
  8.  
  9.  
  10.  
  11.  Note 1:  AHELP5 requires a different file structure for the help file than
  12.    AHELP for Summer '87 (versions 1.x and 2.0) used.  The utility program named
  13.    AHELPUP.EXE converts the previous file structure to the new file structure.
  14.    Use it if you want to UPgrade any help files from AHELP version 1.x or 2.0
  15.    to AHELP5 files.  You do not need to use AHELPUP if you are upgrading from
  16.    AHELP version 2.1.
  17.  
  18.    To use AHELPUP, log into the directory where the old help file exists, and
  19.    enter
  20.  
  21.       AHELPUP [filename]
  22.  
  23.    where [filename] is the name of the old help file.  If you omit the file
  24.    name, AHELPUP will prompt for it.
  25.  
  26.  
  27.  
  28.  Note 2: AHELP5 names its index files differently from AHELP version 1.x or
  29.    2.0; the names of the two index files are derived from the name of the help
  30.    file.  This eliminates the inability of those previous versions of AHELP to
  31.    maintain more than one help file in a given subdirectory.
  32.  
  33.  
  34.  
  35.  Note 3: The parameters passed by Clipper 5.0 to AHELP5 are not consistent with
  36.    those passed by Summer '87 to AHELP.  Consequently, help files created with
  37.    AHELP are of little value to AHELP5.  The ASCII file import capability in
  38.    AHELP5 can partly overcome this Clipper inconsistency, if you use the
  39.    utility program HELPWRIT.EXE to write your old help files out in ASCII
  40.    format, then import them into AHELP5.
  41.  
  42.    To use HELPWRIT, enter
  43.  
  44.       HELPWRIT [filename]
  45.  
  46.    where [filename] is the name (no extension) of the help file.  If you omit
  47.    the file name, HELPWRIT will prompt for it.
  48.  
  49.  
  50.  
  51.         AHELP5.LIB - ADVANCED HELP SYSTEM FOR CLIPPER 5.0 APPLICATIONS
  52.  Version 1.0                              Copyright (C) 1990-1991, Capella Inc.
  53.  
  54.  
  55.  
  56.  Introduction
  57.  ------------
  58.  
  59.  Welcome to AHELP5!  This help system, for use with your Clipper 5.0 
  60.  applications, provides both context-sensitive and generalized help windows.
  61.  Features included with version 1 of AHELP5 (be sure to see version 3, p.7):
  62.  
  63.  * You control whether help windows have no border, a single-line border, or
  64.    a double-line border.
  65.  
  66.  * You control whether the cross-bars drawn inside the help windows have no
  67.    line, a single line, or a double line.
  68.  
  69.  * AHELP5 automatically determines the appropriate intersections.
  70.  
  71.  * You control what colors AHELP5 will use for the help window border, title,
  72.    content, and highlight bar in the help index window.
  73.  
  74.  * You control whether or not the end user has the ability to create or
  75.    modify help windows.
  76.  
  77.  * You control whether or not the help windows have drop shadows.
  78.  
  79.  * AHELP5 automatically positions the help window immediately below the screen
  80.    position of the input variable (e.g., a GET variable) if the window will fit
  81.    there; otherwise, the window appears immediately above the input variable.
  82.  
  83.  * AHELP5 provides a help index; whenever any help window is on the screen,
  84.    the user may press F1 to see the help index.  The help index is another
  85.    window with a scrolling alphabetic listing of help subjects.  The user
  86.    uses the cursor control keys to highlight the subject of interest, and
  87.    presses Enter to see the corresponding help window.  The user may also
  88.    type the first letter of the subject to move the highlight bar immediately
  89.    to the first occurrence of that letter.
  90.  
  91.  * AHELP5 is sensitive to the Clipper environment.  If the cursor is off when
  92.    help is invoked, it will be off when control returns to your application.
  93.    Conversely, if the cursor is on when help is invoked, it will be on when
  94.    control returns to your application.  The same principle applies to colors,
  95.    function keys, insert status, work area, and the status of SET CONSOLE,
  96.    DELETED, ESCAPE, and SCOREBOARD.
  97.  
  98.  * AHELP5 does not use any "wait state" commands (READ, WAIT, ACCEPT, INPUT,
  99.    MENU TO), to avoid conflicts with any pending GETs.  It uses the INKEY()
  100.    function for all keyboard input, with two exceptions: it calls DBEDIT() for
  101.    the help index window and MEMOEDIT() for displaying/editing help text.
  102.  
  103.  
  104.  
  105.  What do you have to do in order to use AHELP5?  Three things:
  106.  
  107.  1.  Insert a call to AHELP in your application with the setup parameters you
  108.      want to use as described in the next section.
  109.  
  110.  2.  Insert the command SET KEY XX TO AHELP in your application.
  111.  
  112.  3.  Compile your application and link, specifying AHELP5.LIB as one of the
  113.      LIB files (AHELP requires both CLIPPER.LIB and EXTEND.LIB).
  114.  
  115.  That's all.  The rest is transparent to your application.
  116.  
  117.  
  118.  Setup
  119.  -----
  120.  
  121.  The application must call AHELP with four parameters before starting the user
  122.  interface, in order to initialize the help system.  During initialization,
  123.  AHELP declares three PUBLIC memory variables:
  124.  
  125.     HELPOPTN   - an array of application options and file names
  126.     HELPCODE   - a character string for use by the application when no input
  127.                  variable is waiting -- AHELP uses the content of `HELPCODE' as
  128.                  its third parameter if the Clipper-passed third parameter is
  129.                  empty
  130.   and
  131.     HELPACTIVE - a logical variable set to true when AHELP is executing, and
  132.                  false otherwise.
  133.  
  134.  Also during initialization, AHELP5 checks for the existence of the help file
  135.  (and creates it if it is missing), and for the existence of the two index 
  136.  files needed (and creates them if they are missing).
  137.  
  138.  
  139.  Setup Syntax:
  140.  
  141.    AHELP( <expC1>, <expN>, <expC2>, <expA> )
  142.  
  143.  where
  144.  
  145.    <expC1> is the name of the application's Help File (one to eight characters)
  146.     
  147.    <expN>  is any value (ignored by AHELP5)
  148.  
  149.    <expC2> is a string of switch values: /Bn/Cn/Dn/En
  150.  
  151.         /Bn defines the help window Border: n=0 means no lines
  152.                                             n=1 means single line
  153.                                             n=2 means double line
  154.  
  155.         /Cn defines the window crossbar:    n=0 means no lines
  156.                                             n=1 means single line
  157.                                             n=2 means double line
  158.  
  159.         /Dn defines drop shadows:           n=0 means shadows are off
  160.                                             n=1 means shadows are on
  161.  
  162.  
  163.         /En defines Edit capability:        n=0 means edit is off
  164.                                             n=1 means edit is on
  165.  
  166.         These switches may appear in any order.  No other switches are defined
  167.         in version 1.  If any switch is missing, default values are:
  168.                 B = 2 (double line border)
  169.                 C = 1 (single line crossbar)
  170.                 D = 0 (drop shadows off)
  171.                 E = 1 (edit on)
  172.  
  173.    <expA>  is the name of a four-element character array containing 
  174.            screen color values:
  175.                 element 1 = the foreground/background colors of the help window
  176.                             content
  177.                 element 2 = the foreground/background colors of the help index
  178.                             highlight bar
  179.                 element 3 = the foreground/background colors of the help window
  180.                             title and bottom-row message
  181.                 element 4 = the foreground/background colors of the help window
  182.                             border
  183.  
  184.         This array is not needed after AHELP5 returns.
  185.  
  186.  Example 1:
  187.  
  188.    PRIVATE HCOLOR[4]
  189.    HCOLOR[1] = "N/W"    && content
  190.    HCOLOR[2] = "W+/B"   && highlight
  191.    HCOLOR[3] = "B/W"    && title
  192.    HCOLOR[4] = "W+/W"   && border
  193.    AHELP("MYAPHELP",0,"/B2/C1/D1/E0",HCOLOR)
  194.              |           |  |  |  |     |
  195.           filename       |  |  |  |   color
  196.                     double  |  |  |   array
  197.                     border  |  |  |   name
  198.                             |  |  |
  199.                        single  |  |
  200.                      crossbar  |  |
  201.                                |  |
  202.                              drop |
  203.                           shadows |
  204.                               on  |
  205.                                   |
  206.                                 edit
  207.                                  off
  208.  
  209.  
  210.  Example 2:
  211.    <declare color array and values as above>
  212.    AHELP("MYAPHELP",0,"",HCOLOR)        && use default switch options
  213.  
  214.  After making this setup call, activate the "hotkey" that will invoke AHELP
  215.  with the SET KEY command.  Examples:
  216.  
  217.    SET KEY 28 TO AHELP         && F1 is the help key
  218.  
  219.    SET KEY 291 TO AHELP        && Alt-H is the help key
  220.  
  221.    SET KEY -9 TO AHELP         && F10 is the help key
  222.  
  223.  
  224.  Execution
  225.  ---------
  226.  
  227.  When the user presses the help key while your application is in any wait
  228.  state, Clipper automatically calls AHELP with three parameters: the name of
  229.  the procedure in control when the key was pressed, the line number that was
  230.  executing, and the name of the wait state input variable.  AHELP5 uses the 
  231.  first and third parameters only (not all applications are compiled with line
  232.  numbers) to construct a "seek key".  It opens the help file and performs a
  233.  seek for that key.
  234.  
  235.  If the key is found, AHELP5 opens a help window and displays the help text;
  236.  the window is opened as close as possible to the input variable screen
  237.  position.  If the key is not found, AHELP5 opens a smaller help window in the
  238.  center of the screen and notifies the user that no help is available.
  239.  
  240.  Either window will show available options at the bottom of the window: Escape
  241.  to cancel help, F1 to call up the help index, and F4 to edit or create the
  242.  help display (if editing is enabled).
  243.  
  244.  Cancel:  If the user presses Escape, AHELP5 closes the help window and returns
  245.  to your application.
  246.  
  247.  Help Index:  If the user presses F1, AHELP5 closes the help window, opens a
  248.  help index window, and displays a scrolling list of help subjects.  The user
  249.  may press Escape again (AHELP5 will close the window and return), or move the
  250.  highlight bar to the desired subject and press Enter to select that subject.
  251.  AHELP5 will close the window and use the subject as the new seek key.
  252.  
  253.  Edit:  If the user presses F4, AHELP5 turns on the cursor and allows the user
  254.  to modify or add text until F2 is pressed (to save any changes).  The user
  255.  may press Escape to abort this process, which restores the original help text
  256.  (if any) and cancels the edit process.  If the user chooses to save changes,
  257.  AHELP5 prompts for a new title for the help text, and for a new index subject;
  258.  both are optional.  The Insert key toggles between insert and overstrike mode
  259.  for title and subject; the default is "insert" mode.  Any title is converted
  260.  to upper case and centered when the help window is recalled, prefixed with the
  261.  words "Help on".  If there is no title, AHELP5 provides the word "Help"
  262.  centered at the top of the window.  If the user specifies an index subject,
  263.  AHELP5 adds it to the help index (see the next page).
  264.  
  265.    If the cursor was not blinking upon entry to AHELP5, creation of a new help
  266.    message will prompt "Is help dependent on cursor position?" in a dialog
  267.    box with two choices: "Independent" or "Dependent" - choosing the Dependent
  268.    option will add the row/column numbers to the seek key.  Note that ACHOICE
  269.    automatically turns off the blinking cursor, but your application must SET
  270.    CURSOR OFF before MENU TO (and then SET CURSOR ON after).  This allows each
  271.    choice in a menu to have an individual help display.
  272.  
  273.  Editing keys available during creation or modification of help text are those
  274.  provided by MEMOEDIT: Ctrl-Y (delete line), Ctrl-T (delete word right), Ctrl-
  275.  left arrow (cursor left one word), Ctrl-right arrow (cursor right one word),
  276.  Ctrl-B (reform paragraph), Ctrl-W (save - same as F2).
  277.  
  278.  AHELP5 is not intended for recursion; if the public variable HELPACTIVE is
  279.  true when AHELP5 is invoked, AHELP5 immediately returns.  Otherwise, it sets
  280.  variable HELPACTIVE to true and continues.  When AHELP5 is done, it resets
  281.  HELPACTIVE to false.
  282.  
  283.  
  284.  Help Index
  285.  ----------
  286.  
  287.  The help index is basically an alphabetized table of contents for generalized
  288.  help (although context-sensitive subjects may also be listed).  The scrolling
  289.  highlight bar is used to point to the subject desired; the cursor keys move
  290.  the highlight bar, and typing a character moves the highlight bar to the first
  291.  occurrence of that character, if any.  Pressing the Enter key selects the
  292.  highlighted entry, and the Escape key cancels the help index.
  293.  
  294.  If edit is enabled, the user may press F4 to edit the highlighted entry,
  295.  Delete to delete the highlighted entry, or Insert to add a new entry.
  296.  
  297.  Edit:  If the user presses F4, AHELP5 opens a small window containing the
  298.  index entry, turns on the cursor, and prompts for any changes.  Pressing Enter
  299.  saves the entry; pressing Escape cancels the edit operation.
  300.  
  301.  Delete:  If the user presses Delete, AHELP5 opens a dialog box to confirm that
  302.  deletion is desired.  The dialog box contains two choices: "Cancel" and
  303.  "Delete".  The cursor keys switch between these choices and Enter selects the
  304.  choice that is highlighted; alternatively, typing the first letter of either
  305.  choice selects that choice.
  306.  
  307.  Insert:  If the user presses Insert, AHELP5 opens a small window containing a
  308.  blank index entry, turns on the cursor, and prompts for the new index entry.
  309.  Pressing Enter saves the new entry; pressing Escape cancels the add operation.
  310.  
  311.  
  312.  
  313.  Structure of Help File
  314.  ----------------------
  315.  
  316.  AHELP5 uses a .DBF (and associated .DBT) for help displays.  The name of the
  317.  help file is determined by the application and passed to AHELP as a parameter
  318.  in the setup call.  If AHELP5 is unable to find the help file in the current
  319.  directory, it creates both the .DBF and .DBT files.
  320.  
  321.  The record layout is:
  322.       Field  Field Name  Type       Width Dec  Usage
  323.           1  HELPKEY     Character     26      Seek Key (see below)
  324.           2  HELPTITL    Character     30      Title for help display
  325.           3  HELPTEXT    Memo          10      Content of help display
  326.           4  HELPSUBJ    Character     30      Subject for help index
  327.           5  HELPKWD1    Character     20      Reserved for version 2
  328.           6  HELPKWD2    Character     20      Reserved for version 2
  329.           7  HELPINDT    Character     26      Reserved for version 2
  330.           8  HELPTROW    Numeric        2      Reserved for version 2
  331.           9  HELPLCOL    Numeric        2      Reserved for version 2
  332.          10  HELPNROW    Numeric        2      Reserved for version 2
  333.          11  HELPNCOL    Numeric        2      Reserved for version 2
  334.       ** Total **                     171
  335.  
  336.  The Seek Key (field HELPKEY) consists of the name of the calling procedure,
  337.  AHELP's first parameter (10 characters); plus the name of the input variable,
  338.  AHELP's third parameter (also 10 characters); and conditionally the row and
  339.  column (three characters each) of the cursor.
  340.  
  341.  
  342.  
  343.  AHELP5 creates and maintains two index files.  Both derive their names from
  344.  the name of the help file by substituting the letters "XS" and "XI" for the
  345.  last two letters of the help file name.  Index file `ffffffXS.nnx' is the seek
  346.  key index.  Index file `ffffffXI.nnx' is the help index index.  The filename
  347.  extension, .NDX or .NTX, is determined by whether you link your application
  348.  with DBFNTX.LIB or its NDX equivalent.
  349.  
  350.  Since AHELP5 adds four to the number of file handles in use, you may need to
  351.  increase FILES= in CONFIG.SYS and SET CLIPPER=Fnn in AUTOEXEC.BAT.  This will
  352.  be determined by how many files your application needs to have open at one
  353.  time.
  354.  
  355.  
  356.  Reserved Names
  357.  --------------
  358.  
  359.  All function and procedure names in AHELP5.LIB begin with the four letters
  360.  "HELP" followed by at least four more characters, except for the "AHELP"
  361.  procedure itself.  Your application should avoid naming any functions or
  362.  procedures in a similar fashion, to eliminate any potential conflict at link
  363.  time.  All variables used internally by AHELP5 are declared LOCAL or PRIVATE,
  364.  with the exception of the three PUBLIC variables HELPACTIVE, HELPCODE, and
  365.  HELPOPTN (all of which also begin with the four letters "HELP").
  366.  
  367.  
  368.  
  369.  Version 3
  370.  ---------
  371.  
  372.  You may order Version 3 of AHELP5 (next page) for ten additional features:
  373.  
  374.  *  Optional path in setup call allows AHELP5 to use a help file and its index
  375.     files in a different drive or directory.
  376.  
  377.  *  Network capability.  AHELP5 opens the help file for shared use only unless
  378.     an update is required.  Then it locks the record long enough for the
  379.     update, and immediately unlocks the record.
  380.  
  381.  *  Drop shadows in any direction, with a vertical width of one or two columns.
  382.  
  383.  *  Help index options: disabled, one level, or two levels; the two-level index
  384.     allows creation of categories of help subjects, for a "super" index.
  385.  
  386.  *  Import help displays from ASCII text files.  During creation of a new help
  387.     display, the user may press F7 to tell AHELP5 to import one or more lines
  388.     of text from a user-specified file.
  389.  
  390.  *  Copy or refer to an existing help display.  During creation of a new help
  391.     display, the user may press F1 to tell AHELP5 to open the help index
  392.     window, "point" to the desired entry, and use that help display.
  393.  
  394.  *  Key word capability.  One or two key words may be specified for each help
  395.     display, and a key word search routine allows lookup by matching against a
  396.     key word prompt.
  397.  
  398.  *  Change the default screen coordinates of either the edit window or the help
  399.     window in the setup call.
  400.  
  401.  *  "Drag" or move any window around the screen and save its new position.
  402.  
  403.  *  Expand or reduce the size of any window and save its new shape.
  404.  
  405.  
  406.  Registration
  407.  ------------
  408.  
  409.  There are no royalty fees for including AHELP5 in your applications.  The
  410.  registration fee for AHELP5 is $50.00 for a single-PC license.  A site license
  411.  is $400.00, and a corporate license (including full source code) is $1000.00.
  412.  A Clipper S'87 version is also available; order both versions and get a 50%
  413.  discount on the second license!  The last page of this user guide is a ready-
  414.  to-mail registration form.
  415.  
  416.  Send your check, money order, or MasterCard/Visa number for the appropriate
  417.  license to:
  418.                    MicroFox
  419.                    P.O. Box 447
  420.                    Richfield, OH 44286-0447
  421.                    U.S.A.
  422.  
  423.  We will send you version 3 of AHELP5, and add your name(s) to our list of
  424.  users for future upgrade notices and other offers.  Specify diskette size(s).
  425.  
  426. <End of AHELP5.DOC>
  427.  
  428.  
  429.                       AHELP5 REGISTRATION AND ORDER FORM
  430.  
  431.    Send to:        MicroFox Co.                  P.O. # _________________
  432.                    P.O. Box 447
  433.                    Richfield, OH                   DATE _________________
  434.                    44286-0447  U.S.A.
  435.    ________________________________________________________________________
  436.  
  437.    Order both S'87 AND 5.0 and take 50% off second license at same level!
  438.  
  439.      Single-User License ..................................... $50 U.S.
  440.  
  441.             Quantity:  Summer '87 ____   5.0 ____    SUBTOTAL  $_________ 
  442.  
  443.  
  444.      Site License (unlimited use per site) ............... $400.00 U.S.
  445.  
  446.             Quantity:  Summer '87 ____   5.0 ____    SUBTOTAL  $_________ 
  447.  
  448.  
  449.      Corporate License (unlimited use within enterprise): $1000.00 U.S.
  450.      (Includes full source code.)
  451.             Quantity:  Summer '87 ____   5.0 ____    SUBTOTAL  $_________ 
  452.  
  453.  
  454.      Each License includes a master disk.      LICENSES TOTAL  $_________
  455.    ________________________________________________________________________
  456.  
  457.  
  458.      Ohio residents add 5.5% sales tax              SALES TAX  $_________
  459.  
  460.      Shipping and handling charges:
  461.                         U.S.A. ...... $2 each        SHIPPING  $_________
  462.                         Canada ...... $3 each                          
  463.                         All others .. $5 each  
  464.                                                         TOTAL  $_________
  465.    ________________________________________________________________________
  466.  
  467.  
  468.      Payment:  P.O. __    Check __    Money Order __    Visa __    M/C __
  469.  
  470.  
  471.      MasterCard/Visa # ________________________   Exp. Date _____________
  472.  
  473.  
  474.      Signature __________________________   (if credit card order)
  475.    ________________________________________________________________________
  476.      
  477.  
  478.      Ship To:    Name ___________________________________________________
  479.  
  480.               Company ___________________________________________________
  481.  
  482.               Address ___________________________________________________
  483.  
  484.                       ___________________________________________________
  485.  
  486.                       ___________________________________________________
  487.  
  488.                 Phone ___________________________________________________
  489.  
  490.        Diskette media:     5.25" acceptable ____     3.5" required ____
  491.  
  492.